<html>
<head>
<script type="text/javascript" src="../../../examples/sh_main.js"></script>
<script type="text/javascript" src="../../../examples/sh_java.js"></script>
<script type="text/javascript" src="../../../examples/sh_javascript.js"></script>
<link REL ="stylesheet" TYPE="text/css" HREF="../../../examples/sh_nedit.css" TITLE="Style">
<meta NAME="author" CONTENT="Judit Vasko-Szedlar">
<link REL ="stylesheet" TYPE="text/css" HREF="../../marvinmanuals.css" TITLE="Style">
<title>I/O</title>
</head>
<body onload="sh_highlightDocument();">

<h1>I/O</h1>

<h2>Table of contents</h2>

<ul>
    <li><a href="#sources">Sources of data</a></li>
    <li><a href="#formats">Supported formats</a>
        <ul>
            <li><a href="#get_formats">Listing all available formats programmatically</a></li>
        </ul>
    </li>
    <li><a href="#import">Import</a>
        <ul>
            <li><a href="#import_api">Import using the API</a>
                <ul>
                    <li><a href="#import_string">Importing from String</a></li>
                    <li><a href="#import_stream">Importing from InputStream</a></li>
                    <li><a href="#import_multi">Importing a multi-molecule file</a></li>
                    <li><a href="#import_mrecord">Importing with MRecordImporter</a></li>
                    <li><a href="#import_props">Importing molecular properties</a></li>
                </ul>
            </li>
            <li><a href="#import_applets">Import into Marvin Applets</a>
                <ul>
                    <li><a href="#import_jmview1">Import into MarvinView Applet with the <code>mol</code> parameter</a></li>
                    <li><a href="#import_jmview2">Import into MarvinView Applet with the <code>cell</code> parameter</a></li>
                    <li><a href="#import_jmsketch">Import into MarvinSketch Applet with JavaScript</a></li>
                </ul>
            </li>
            <li><a href="#import_beans">Import into Marvin Beans</a>
            </li>
        </ul>
    </li>
    <li><a href="#export">Export</a></li>
</ul>

<hr>

<h2><a name="sources" class="anchor">Sources of data</a></h2>
When importing structures to ChemAxon tools, we will refer to different sources the data cames from:
<ul>
<li>Structure file where location is given with absolute or relative path</li>
<li>Structure file where location is given with URL</li>
<li>Molecule source text (e.g. pre-read content of a structure file) in various formats</li>
<li>Molecule object from another application or database</li>
</ul>

<h2><a name="formats " class="anchor">Supported formats</a></h2>

<p>The detailed documentation about the supported file formats is <a href="../../formats/formats.html">here</a>.</p>

<h4><a name="#get_formats">Listing all available formats programmatically</a></h4>

<p>Programmatic listing of the available file formats is available via the
    <a href="../beans/api/chemaxon/formats/MFileFormat.html"><code>MFileFormat</code></a> and
    <a href="../beans/api/chemaxon/formats/MFileFormatUtil.html"><code>MFileFormatUtil</code></a> API.</p>

<p>The code below lists the available molecule formats:</p>
<pre class="sh_java">
  MFileFormat[] formats = MFileFormatUtil.findFormats(
      null,
      MFileFormat.F_EXPORT,
      MFileFormat.F_EXPORT | MFileFormat.F_ARCHIVE | MFileFormat.F_GRAPHICS);     
</pre>

<p>In this example archive formats (like GZip or BASE64) are excluded by the MFileFormat.F_ARCHIVE flag, graphics formats
    are excluded by the MFileFormat.F_GRAPHICS flag given by the 3rd parameter.
</p>


<h2><a name="import" class="anchor">Import</a></h2>
<p>Molecule import is the operation when sources of data, i.e. structures defined in various formats are
converted to Molecule objects so that ChemAxon applications can operate with them.
</p>

<h3><a name="import_api" class="anchor">Import using the API</a></h3>

<p>The most frequently used API for molecule import is defined in <a href="../beans/api/chemaxon/formats/MolImporter.html"><code>chemaxon.formats.MolImporter</code></a>.</p>
<p>The drawback of the MolImporter API is that applets are unable to use them.
A newer API of ChemAxon that can also be used by applets is <a href="../beans/api/chemaxon/marvin/io/MRecordImporter.html"><code>chemaxon.marvin.io.MRecordImporter</code></a>.</p>

<h4><a name="import_string" class="anchor">Importing from String</a></h4>
Importing one molecule where the molecule source is available as String.
<pre class="sh_java">
    String molSource = "CCC(N)c1cc(Cl)cc(C(N)CC)c1Br";
    try {
        Molecule mol = MolImporter.importMol(molSource);
        // do something with the molecule
    } catch (MolFormatException e) {
        e.printStackTrace();
    }
</pre>

For a complete source code, please see <a href="../../../examples/io/basic/ImportMoleculeSource.java"><code>ImportMoleculeSource.java</code></a>.

<h4><a name="import_stream" class="anchor">Importing from InputStream</a></h4>
Importing one molecule where the molecule source is available via an InputStream.
<pre class="sh_java">
    try {
        MolImporter mi = new MolImporter(stream);
        Molecule mol = mi.read();
        // do something with the molecule
        mi.close();
    } catch (IOException e) {
        e.printStackTrace();
    }
</pre>

For a complete source code, please see <a href="../../../examples/io/basic/ImportFromStream.java"><code>ImportFromStream.java</code></a>.

<h4><a name="import_multi" class="anchor">Importing a multi-molecule file</a></h4>
<p>
<b>Importing molecules from a multi-molecule file given with URL:</b>
</p>
<pre class="sh_java">
    try {
        URL url = new URL(path);
        MolImporter importer = new MolImporter(url.openStream());
        Molecule mol;
        while ((mol = importer.read()) != null) {
            // do something with the molecule
        }
        importer.close();        
    } catch (IOException e) {
        e.printStackTrace();
    }
</pre>

For a complete source code, please see <a href="../../../examples/io/basic/ImportMultiMoleculeFile.java"><code>ImportMultiMoleculeFile.java</code></a>, <code>importMolecule</code> method.

<h4><a name="import_mrecord" class="anchor">Importing with MRecordImporter</a></h4>
<p>With this method importing with machines having multiple processors will be concurrent,
otherwise single-threaded.</p>
<pre class="sh_java">
    try {
        URL url = new URL(path);
        MolInputStream mis = new MolInputStream(url.openStream(), null, null, null);
        MRecordImporter importer = new MRecordImporter(mis, null);
        MDocument mDocument;
        while ((mDocument = importer.readDoc()) != null) {
            Molecule mol = (Molecule) mDocument.getMainMoleculeGraph();
            // do something with the molecule
        }
        importer.close();
    } catch (MRecordParseException ex) {
        ex.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
</pre>

For a complete source code, please see <a href="../../../examples/io/basic/ImportMultiMoleculeFile.java"><code>ImportMultiMoleculeFile.java</code></a>, <code>importMolecule2</code> method.

<h4><a name="import_props" class="anchor">Importing molecular properties</a></h4>

<p>In case we know the name of the properties, we can use the following code to get the values in text format:</p>
<pre class="sh_java">
    String value = molecule.getProperty(LOGP_FIELD); //LOGP_FIELD is the name of the property
</pre>

<p>Otherwise we need to go through the property names. An example is below:</p>
<pre class="sh_java">
    for (int i=0; i&lt;molecule.getPropertyCount(); i++) {
        String key = molecule.getPropertyKey(i); // name of the property
        String value = molecule.getProperty(key); // the property value
    }
</pre>

<p>For a complete source code, please see <a href="../../../examples/io/basic/ImportProperties.java"><code>ImportProperties.java</code></a>.</p>

<h3><a name="import_applets" class="anchor">Import into Marvin Applets</a></h3>

<p>There are two possible ways of importing molecules to MarvinSketch and MarvinView applets.</p>
<p>The simpler way is to use applet parameters. This is the recommended way of importing molecules when the applet is loaded.</p>

<p>The other way is to use JavaScript calls. This allows importing molecules a while after the applet is loaded, typically invoked by a user interaction.
Both MarvinSketch and MarvinView applets have convenience methods to import molecules with JavaScript calls.</p>
<p><a href="../../../help/developer/applets/api/JMSketch.html#setMol%28java.lang.String%29"><code>JMSketch.setMol(String)</code></a>
takes molecule source, URL or filename as an argument.</p>
<p>The corresponding <a href="../../../help/developer/applets/api/JMView.html#setMol%28java.lang.String%29"><code>JMView.setMol(String)</code></a>
method of the MarvinView Applet is very similar. The consecutive calls of this method will place molecules in separate cells.</p>

<h4><a name="import_jmview1" class="anchor">Import into MarvinView Applet with the <code>mol</code> parameter</a></h4>
<p>With the <a href="../viewman.html#parameters.mol"><code>mol</code></a> parameter, molecules of a multi-molecule file will be loaded to separate cells.</p>
<pre class="sh_javascript">
    mview_begin("../../..",430,440);
    // Setting number of rows, columns and the layout
    mview_param("mol","../../../mols-2d/mols.sdf");
    mview_end();
</pre>

For a complete example please visit: <a href="../../../examples/applets/view/sdtable.html">MarvinView Example - Loading molecules from an SD file to a molecule table</a>

<h4><a name="import_jmview2" class="anchor">Import into MarvinView Applet with <code>cell</code> parameter</a></h4>
<p>The <a HREF="../viewman.html#advanced.cell"><code>cell</code></a> parameter defines the contents of each cell individually.</p>

<pre class="sh_javascript">
    mview_begin("../../..", 300, 300);
    mview_param("rows", "2");
    mview_param("cols", "2");
    mview_param("cell0", "|../../../mols-2d/caffeine.csmol");
    mview_param("cell1", "|O[C@H](\C=C\[C@@H](O)C1=CC=CC=C1)C2=CC=CC=C2");
    mview_end();
</pre>
For a complete example please visit: <a href="../../../examples/applets/view/advancedtable.html">MarvinView Example - Creating an advanced molecule table</a>

<h4><a name="import_jmsketch" class="anchor">Import into MarvinSketch Applet with JavaScript</a></h4>

<pre class="sh_javascript">
    function importMol(opts) {
            if(document.MSketch != null) {
                    var s = document.MolForm.MolTxt.value; //Value is read from a HTML text area
                    document.MSketch.<a HREF="../../../help/developer/applets/api/JMSketch.html#setMol(java.lang.String, java.lang.String)">setMol</a>(s, opts);
            } else {
                    alert(&quot;Cannot import molecule:\n&quot;+
                          &quot;no JavaScript to Java communication in your browser.\n&quot;);
            }
    }
</pre>
For a complete example, please visit: <a href="../../../examples/applets/sketch/js_io.html">MarvinSketch Example - Import/export of built-in and
	user defined molecule formats in JavaScript</a>


<h3><a name="import_beans" class="anchor">Import into Marvin Beans</a></h3>

<h4><a name="import_sketch" class="anchor">Import into MarvinSketch</a></h4>

<h4><a name="import_view" class="anchor">Import into MarvinView</a></h4>

<h2><a name="export" class="anchor">Export</a></h2>

</body>
</html>